---
title: Understanding Plugins
description: Learn how plugins add features like zooming, searching, and annotations to your headless PDF viewer.
---

# Understanding Plugins

Plugins are the heart of EmbedPDF's headless architecture. They are modular packages that add specific features and capabilities to your core viewer. This à la carte approach ensures your application remains lean, loading only the functionality you actually need.

Think of the `<EmbedPDF>` component as a smartphone: it's powerful on its own, but it's the apps (plugins) you install that give it new features like navigation, social media, or games.

## How Plugins Work

Adding a new feature to your viewer follows a simple three-step process:

### 1. Install the Plugin Package

Each plugin is its own NPM package. For example, to add zooming capabilities, you would install the zoom plugin:

```sh npm2yarn
npm install @embedpdf/plugin-zoom
````

### 2. Register the Plugin

Next, you import the plugin's `...PluginPackage` and register it in the `plugins` array that you pass to the `<EmbedPDF>` component. This is done using the `createPluginRegistration` helper function.

```tsx filename="PDFViewer.tsx" {4, 14-16}
import { createPluginRegistration } from '@embedpdf/core';
import { EmbedPDF } from '@embedpdf/core/react';
// ... other imports
import { ZoomPluginPackage } from '@embedpdf/plugin-zoom/react';

const plugins = [
  // ... other essential plugins like Loader, Viewport, etc.
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Add the zoom plugin to the array
  createPluginRegistration(ZoomPluginPackage, {
    defaultZoomLevel: 1.5, // You can pass options here!
  }),
];

// ... rest of your component
```

Registering the plugin activates its core logic and makes its features available to the rest of your application.

### 3. Use the Plugin's Components and Hooks

Once a plugin is registered, you can use its associated React components and hooks to build your UI. For example, the zoom plugin provides a `<MarqueeZoom />` component for drag-to-zoom functionality and a `useZoom` hook to control zoom levels from a toolbar.

```tsx filename="ZoomToolbar.tsx"
import { useZoom } from '@embedpdf/plugin-zoom/react';

export const ZoomToolbar = () => {
  const { provides: zoomProvides, state: zoomState } = useZoom();
 
  if (!zoomProvides) {
    return null;
  }

  return (
    <div>
      <span>Current Zoom: {Math.round(zoomState.currentZoomLevel * 100)}%</span>
      <button onClick={zoomProvides.zoomOut}>-</button>
      <button onClick={zoomProvides.zoomIn}>+</button>
      <button onClick={() => zoomProvides.requestZoom(1.0)}>Reset</button>
    </div>
  );
};
```

This clear separation of logic (the plugin) from the view (your components) gives you complete control over your UI.

### 4. Add the Component to Your Viewer

Finally, import and place your new `<ZoomToolbar />` component **inside** the `<EmbedPDF>` provider. This is essential, as it allows the `useZoom` hook to access the context provided by the `ZoomPluginPackage`.

```tsx filename="PDFViewer.tsx" {4, 12-13, 19}
import { EmbedPDF } from '@embedpdf/core/react';
// ... other imports
import { Viewport } from '@embedpdf/plugin-viewport/react';
import { ZoomToolbar } from './ZoomToolbar'; // 1. Import the toolbar

// ... plugins array and PDFViewer component setup
export const PDFViewer = () => {
  // ...
  return (
    <div style={{ height: '500px', border: '1px solid black', display: 'flex', flexDirection: 'column' }}>
      <EmbedPDF engine={engine} plugins={plugins}>
        <div style={{display: 'flex, height: '100%', flexDirection: 'column'}}>
          <ZoomToolbar /> {/* 2. Add the component here */}
          <div style={{ flex: 1, overflow: 'hidden' }}>
            <Viewport>
              {/* ... Scroller and RenderLayer ... */}
            </Viewport>
          </div>
        </div>
      </EmbedPDF>
    </div>
  );
};
```

### 5. Live Demo
This is the result of the code above—a fully functional PDF viewer with zoom controls that you built from the ground up.

import { PDFViewer } from './code-examples/zoom-example';

<PDFViewer />

## Types of Plugin Features

Plugins can provide several types of tools:

  - **Core Logic:** Some plugins work entirely in the background to manage state (e.g., `ScrollPluginPackage`).
  - **React Components:** Most plugins offer functional components that you place in your viewer to add UI features (e.g., `<RenderLayer />`, `<SelectionLayer />`, `<MarqueeZoom />`).
  - **React Hooks:** Functions like `useZoom()` or `useSearch()` allow your custom components to access plugin data and trigger actions.

By combining plugins, you can compose a feature-rich PDF experience that is perfectly tailored to your application's design and needs.